TMSAgent v2.x has undergone a major redesign of its internal architecture from that used in TMSAgent v1.x.

These changes may effect existing applications when upgrading from a previous version of TMSAgent.  The changes are as follows:


Error Handling
--------------
- The following error defines are no longer used:

	AGENT_ERROR_FILENOTFOUND
	AGENT_ERROR_INTERNALNULLRETURNED
	AGENT_ERROR_UNKNOWNERROR

- Exceptions thrown internally are no longer discarded internally.  After firing the TMSAgent::OnError event handler, exceptions are re-thrown into user code for handling.  Consequently, all class methods that used to return error codes have had their return values removed.  The error code is accessible via the EMSAgentError::HResult property.


TMSAgent
--------
- All custom error codes have been incremented by 60.

- A new property, VersionLong, has been added.  This returns MS Agent's version in a long, where the HIWORD is the major version and the LOWORD is the minor version.  The previous Version property still exists, utilizing VersionLong internally.

- Two new properties, LastErrorCode and LastErrorMsg, have been added.  They return information about the last error thrown by TMSAgent.  Particularly useful for testing for errors when a property returns a value that may or may not be an error value, such as a boolean or TFontCharset.

- The overloaded version of the ShowDefaultCharacterProperties() method has been removed in favor of having a method that can take optional parameters instead.  If these parameters are both set to AGENT_ORIGINAL_VALUE, the dialog window will display in its last known location.

- The X and Y parameters of ShowDefaultCharacterProperties() have been changed from int to short.

- The RaiseErrors property has been removed.

- The Connected property has been moved from published to public instead.

- An additional ErrorCode parameter has been added to the OnError event.

- The X and Y parameters of the OnClick, OnDblClick, OnDragStart, OnDragComplete, OnMouseMove, and OnMove events have been replaced with a TPoint parameter.

- The Cause parameter of the OnVisibleState event has been changed from an int to a new enum type, TAgentVisibleState.

- The Cause parameter of the OnListeningState event has been changed from an int to a new enum type, TAgentListenState.

- The Cause parameter of the OnHelpComplete event has been changed from an int to a new enum type, TAgentHelpState.

- The Cause parameter of the OnMove event has been changed from an int to a new enum type, TAgentMoveCause.

- The BecameVisible parameter of the OnBalloonVisible event has been renamed to State, and changed from a bool to a new enum type, TAgentBalloonState.

- The StartingIdle parameter of the OnIdle event has been renamed to State, and changed from a bool to a new enum type, TAgentIdleState.

- The BecameActive parameter of the OnActiveInputChange event has been renamed to State, and changed from a bool to a new enum type, TAgentInputState.

- The Status parameter of the OnActiveClientChange event has been changed from an int to a new enum type, TAgentClientState.


TAgentAudioOutputProperties
---------------------------
- The Status property has been changed from an int to a new enum type, TAgentActiveState.


TAgentBalloon
-------------
- The TBalloonStyleOption enum has been renamed to TAgentBalloonStyle

- The TBalloonStyle Set has been renamed to TAgentBalloonStyles

- The values of TAgentBalloonStyles (formerly TBalloonStyle) are now preceeded by a "bs" prefix, and a new bsError value has been added

- The values of TBalloonFontStyles are now preceeded by a "bfs" prefix, and a new bfsError value has been added


TAgentCharacter
---------------
- A new property, VersionLong, has been added.  This returns the character's version in a long, where the HIWORD is the major version and the LOWORD is the minor version.  The previous Version property still exists, utilizing VersionLong internally.

- A new property, IsDefault, as been added.  This returns whether the character is MSAgent's default character, which is the character that is loaded whenever a filename is not specified.

- A new property, FileFolder, has been added.  This returns the path to the folder where the character file is located.

- A new property, FileSpec, has been added.  This returns the original path passed to TAgentCharacters::Load().

- The FileName property now returns just the filename of the character with no path info.  It also now returns an empty string instead of "Default" if MSAgent's default character is loaded.

- A new method, GestureAt(), has been added.  This allows for the character to gesture at arbitrary screen coordinates.

- A new method, Prepare(), has been added.  This is used to pre-load a character's state, animation, or wave file when using a remotely-loaded ACF character file.

- New overloaded versions of MoveToXY() and ShowPopupMenu() have been added which take TPoint parameters.

- The ShowCharacterFirst parameter of MoveToXY() has been removed.

- The PlayThinkAnim parameter of Think() has been removed.

- The AutoPopupAgentMenu property has been renamed to AutoPopupMenu, and its behavior has been changed.  Previously, when the character was right-clicked on (or the ShowPopupMenu() method called) and AutoPopupAgentMenu was set to true, the character's native popup menu would be displayed.  Now, when AutoPopupMenu is set to true, the TPopupMenu assigned to the PopupMenu property will be displayed if assigned, otherwise the native popup menu will be displayed instead.

- The X and Y parameters of MoveToXY() and ShowPopupMenu() have been changed from int to short.

- The ActiveState property has been changed from an int to a new enum type, TAgentActiveState.

- The MoveCause property has been changed from an int to a new enum type, TAgentMoveCause.

- The SRStatus property has been changed from an int to a new enum type, TAgentListenStatus.

- The Type parameter of Prepare() have been changed from an int to a new enum type, TAgentPrepareType.

- The RequestType parameter of StopAll() has been changed from an int to a new Set type, TAgentStopTypes.

- The internal PointerFactor variable has been exposed as a public property.  This value is used to specify the factor percentage of the location where the character's outstretched hand is in relation to the overall height.  Used for automatic positioning purposes.

- A WaveFile parameter has been added to the Speak() method, for allowing the playback of sound files.

- The overloaded versions of the Hide(), Listen(), MoveToXY(), Show(), Stop(), StopAll(), and Think() methods have been removed in favor of having methods that can take optional parameters instead.

- When an error occurs while reading the OriginalSize or Size property, the returned values are now set to error codes rather than -1, where the cx value is set to AGENT_ERROR_VALUEOUTOFRANGE and the cy value is set to the specific error code that occured.

- When an error occurs while reading the Width or Height properties, the returned values are now set to error codes rather than -1.

- When an error occurs while reading the Position property, the returned values are now set to error codes rather than -1, where the x value is set to AGENT_ERROR_VALUEOUTOFRANGE and the y value is set to the specific error code that occured.

- When setting the Width, Height, or Size properties, the character's original dimensions are only restored when using the new AGENT_ORIGINAL_VALUE define as the new sizes.

- When an error occurs while reading the Left or Top properties, the returned values are now set to error codes rather than -1.

- The Speak() and Think() methods now return AGENT_ERROR_VALUEOUTOFRANGE instead of AGENT_ERROR_INTERNALNULLRETURNED when text and url parameters are both empty.

- When calling the Interrupt() or Wait() methods with a TAgentCharacter* parameter, they now return AGENT_ERROR_OBJECTNOTFOUND instead of AGENT_ERROR_INTERNALNULLRETURNED if an invalid character object is passed in.

- When an error occurs while reading the HelpContextID property, it now returns an error code instead of -1.

- When an error occurs while reading the HelpContextID or LanguageID properties, they now return an error code instead of -1.

- The TTSEngineID and SREngineID properties have been renamed to TTSModeID and SRModeID, respectively.


TAgentCharacters
----------------
- A new method, LoadDefaultCharacter(), has been added.  This is used to load the MSAgent's default character.

- The overloaded version of the Load() method has been removed.  The File parameter of the remaining version of Load() is no longer optional.  To load the default character, use the new LoadDefaultCharacter() method instead.

- When calling the Load() method, it no returns ERROR_FILE_NOT_FOUND if the requested file is not found.

- When calling the Unload() method with a TAgentCharacter* parameter, it now returns AGENT_ERROR_OBJECTNOTFOUND instead of AGENT_ERROR_INTERNALNULLRETURNED if an invalid character object is passed in.

- Two new properties, CharacterFolder and InstalledCharacters, have been added.  CharacterFolder retrieves the full path to the "<WINDIR>\MSAgent\Chars" folder.  InstalledCharacters retreives a list of filenames of the characters that are installed in the CharacterFolder.

- A new overloaded version of Character() that takes a HWND parameter has been added.


TAgentCommands
--------------
- The DefaultID property has been renamed to DefaultCommand.

- A new property, DefaultCommandID, has been added.  This works the same as the DefaultCommand property, except that it accepts a long instead of a TAgentCommand* as a parameter.

- When an error occurs while reading the HelpContextID property, it now returns an error code instead of -1.

- When calling the Remove() method with a TAgentCommand* parameter, it now returns AGENT_ERROR_OBJECTNOTFOUND instead of AGENT_ERROR_INTERNALNULLRETURNED if an invalid command object is passed in.


TAgentCommandWindow
-------------------
- When an error occurs while reading the Position or Size properties, the values are now set to error codes rather than -1, where the x value is set to AGENT_ERROR_VALUEOUTOFRANGE and the y value is set to the specific error code that occured.


TAgentPropertySheet
-------------------
- When an error occurs while reading the Position or Size properties, the values are now set to error codes rather than -1, where the x value is set to AGENT_ERROR_VALUEOUTOFRANGE and the y value is set to the specific error code that occured.

- The Page property now takes a new TAgentPropertyPage enum type instead of an AnsiString.

- When an error occurs while reading the Page property, it now returns either ppUnknown or ppError instead of an empty string.